Overview
Welcome to WinHelp BugHunter (32-bit)

WinHelp BugHunter allows you to quickly diagnose and fix problems that can occur when linking Help systems to Windows applications.

You’ll find WinHelp BugHunter particularly useful when:

•	You’re testing the Help links in an application and see the message "Help Topic Does Not Exist" instead of your Help topic.

•	Your Help system appears when called from an application, but the wrong topic is displayed.

•	You want to quickly determine if a particular map number is used in your Help system.

•	You want to test TCard Help.

There are other advanced options. See WinHelp BugHunter Options.

About Context-sensitive Help

When a Help system is linked to a Windows application, the Help system is referred to as "context-sensitive Help". This kind of Help provides information about a particular part of the application and is available when users press <F1> within applications, click Help buttons at dialogs, or click question marks in the upper-right corner of dialogs, and then click a particular field.

When context-sensitive Help is implemented, an application tells the WinHelp engine to display a certain help file and topic when the user requests help. The application uses a number (called a map ID or context ID)  to identify a specific topic. Normally, the number is assigned a textual context string (such as IDH_My_First_topic) and, for convenience, both the programmer and the writer use this string instead of the actual number. The communication between the application and the Help engine is still the number however. Problems can arise when the link in the application source code does not match a number (map ID) in the Help system. Such discrepancies result in WinHelp displaying "Help Topic Does Not Exist" messages. WinHelp BugHunter shows you the number (or map ID)  that the application is calling, and thus allows you to quickly diagnose and eliminate these kinds of problems.


System requirements

•	On Windows 95, 98, NT 4.0, and 2000 systems, WinHelp BugHunter (32-bit) allows you to troubleshoot any WinHelp 4 Help system.

If you are creating a WinHelp 3 system and your development PC is a Windows NT system, you should use the 16-bit version of BugHunter, called WinHelp BugHunter+ (16-bit). To install the 16-bit version, choose to install the tools for WinHelp 3 when you install RoboHELP Office.


How context-sensitive Help works

When context-sensitive Help is implemented, an application tells the WinHelp engine to display a certain help file and topic when the user requests help. The application uses a number (called a map ID or context ID)  to identify a specific topic. Normally, the number is assigned a textual context string (such as IDH_My_First_topic) and, for convenience, both the programmer and the writer use this string instead of the actual number. The communication between the application and the Help engine is still the number however.

The link between a topic’s context string and map ID is through a map file. Each topic in the Help file is listed in the map file and assigned a map ID (also called a context ID). Sometimes the Help author generates the map file (RoboHELP can generate it automatically) and provides the list of map IDs to the developer. Sometimes the developer will provide the map file to the Help author. The map file usually has an .HH extension. If you open a map file in a text editor, it often contains lines that look like this:

#define  FILENAME_My_Help_Topic_  101

In this example, FILENAME refers to the document name. My_Help_Topic is the context string and 101 is the map ID (or context ID).

You can easily view the context string (also called a topic ID) and the map ID for a particular topic in RoboHELP by choosing Topic Properties. The topic ID is listed on the General tab and the map ID is listed on the Advanced tab.

What causes context-sensitive Help to break down?

The application developer creates a WinHelp call that includes the name of your Help file and the map ID of the specific topic to display. As you can imagine, problems will arise if:

•	The programmer uses the wrong map ID or wrong Help file name in the WinHelp call

•	The Help author has assigned the wrong map ID to the Help topic

•	A topic was not assigned a map ID

•	A map ID has been changed


Getting Started with BugHunter
Starting WinHelp BugHunter

You can start WInHelp BugHunter directly from within RoboHELP, or you can start it standalone from within RoboHELP Office.

To start WinHelp BugHunter from RoboHELP:

•	From the RoboHELP Explorer Tools tab, double-click WinHelp BugHunter (32-bit) [image]. The WinHelp BugHunter window displays.

To start WinHelp BugHunter from RoboHELP Office:

1	From the Start menu, select Programs, RoboHELP Office, RoboHELP Office. The RoboHELP Office Starter appears.

2	Double-click WinHelp BugHunter [image]. The WinHelp BugHunter window displays.

Tip:

Once you’ve started WinHelp BugHunter, from the View menu, select Options then Always on Top. Always on Top allows you to always see the BugHunter window while it’s open on your desktop. (It’s especially handy if you work with a small monitor.)


Using WinHelp BugHunter 32-bit
Overview of using WinHelp BugHunter

There are two main activities involved in finding and repairing a broken context-sensitive Help link:

•	Use WinHelp BugHunter to determine what is being called from the application. WinHelp BugHunter will show you the context ID (map ID) and Help file name that is being called from an application. In the following example, the context ID is 103 and the Help file name is BH32SAMP.HLP.

•	Use the information to resolve the incorrect link.

What do you want to do?

Start WinHelp BugHunter

Determine what the application is calling

Learn about repairing incorrect links


Determining what is being called from the application

1	Start WinHelp BugHunter.

2	Start the application you need to debug.

3	Arrange your work area and resize the windows so that you can see both your application and WinHelp BugHunter.

4	Repeat the action that causes the error you need to fix. For example, click the Help button that is calling the wrong topic. Any calls that the application makes to WinHelp are captured and displayed in the WinHelp BugHunter window.

5	Make a note of the Help file name and context ID (map ID) displayed by WinHelp BugHunter. You’ll use this information to repair the broken link.

See Also

Overview of repairing the broken link


Repairing the broken link
Overview of repairing broken links

There are several  ways to approach fixing a broken link, depending on the scenario. You should discuss the problem and possible solutions with your application developer to determine the best method to choose. Here are some scenarios you may encounter:

One of the WinHelp calls is referencing the wrong ID

For example, the WinHelp call is referencing context ID 103 and it should be referencing context ID 104. In this situation, the Help author can update the context ID or the developer can reprogram the WinHelp call. Discuss this with your developer to decide who will repair the problem.

The WinHelp call is referencing an old Help file name

The Help file name has changed. In this situation, the Help author can change the name of the compiled Help file (using Windows Explorer) or the developer can reprogram the WinHelp call.

One of the WinHelp calls is referencing an ID that does not exist

This may occur if the Help author has not created the topic yet. In this case, the Help author can create a topic with the specific context ID.

There are several WinHelp calls referencing several different IDs but you’ve decided you want them to call one single topic.

In this case, the Help author can alias the context IDs to a single topic.

What do you want to do?

Update a context ID

Create a new topic with a specific context ID

Learn about creating an Alias


Changing the context ID for a Help topic

1	Open the Help project in RoboHELP.

2	Navigate to the topic whose map ID you want to change.

3	From the RoboHELP Edit menu, choose Properties.

4	Click the Advanced tab.

5	In the Map ID box, type the correct Map ID.

6	Click OK.

7	Recompile the project.

8	Place the HLP file in the same folder as the application and retest the link.


Creating a new topic with a specific ID

1	Open the Help project in RoboHELP.

2	Click the Create Topic button.

3	Click the Advanced tab.

4	In the Map ID field, type a specific Map ID.

5	Complete any other options in the box.

6	Click OK.

7	Recompile the project.

8	Place the HLP file in the same folder as the application and retest the link.


Creating an alias
Overview of creating an alias

In this example, you have several WinHelp calls referencing several map IDs. For example, there are WinHelp calls referencing map IDs 104, 105 and 106. You’ve decided to create one Help topic that should appear when any of those IDs is called.

•	First you need to determine if the map IDs 104, 105 and 106 are in your project.

•	If they are not in the project, you will add them, then alias them.

•	If they are in the project, simply alias them.

What do you want to do?

Determine if the map IDs are in your project

Add a map ID to the project

Alias a map ID


Determine if the map IDs are in your project

1	Open your project in RoboHELP.

2	Open the RoboHELP Explorer Project view in the left pane.

3	Open the Project folder.

4	Open the All Map IDs folder.

5	Find out if the map IDs (in this example 104, 105 and 106) are in your project. From the RoboHELP Explorer Edit menu, click Find Map ID.

6	Type one of the map IDs (for example 104).

If the map ID is in your project, it will be selected in Project view and you can proceed to Alias it. If the map ID is not in the project, you will receive a message indicating that it is not in the project and you will need to add them.

See Also

Adding a map ID to the project

Aliasing a map ID


Aliasing a map ID

1	From RoboHELP Explorer open the Project folder.

2	Right click the Map IDs folder.

3	Open the All Map IDs folder.

4	Find the map ID (in this example, find map ID 104).

5	Right click the ID and choose New Alias.

6	Select the topic ID of the topic that should be displayed.

7	Repeat the above steps for additional aliases for map IDs 105 and 106.

8	Save and compile the Help project then re-test the links. All three WinHelp calls should reference the same topic.

See Also

Determine if the map IDs are in your project

Adding a map ID to the project


If the map ID is not in your project

1	Open the Project folder.

2	Right click the Map IDs folder and choose New Map ID.

3	In the Map String field, type in some placeholder text.

4	In the Map Number field, type one of the map IDs you are adding to the project (in this example 104, 105 or 106).

5	Click OK.

6	Now alias the map ID to the topic.

See Also

Aliasing a map ID


BugHunter Options
Overview of WinHelp BugHunter options

WinHelp BugHunter provides different options that you can set while using the program. These options include:

•	Spy on WinHelp
When this option is enabled, WinHelp BugHunter 32-bit reports all WinHelp activities in its output window. Reported activities include macros, so if your project makes use of these, you will want this option enabled. Be sure that Spy on WinHelp is enabled if you are debugging a Help button. In general, this option reports activities of greatest interest to Help Authors. Windows messages (notably WM_HELP and WM_TCARD) are not captured by this option (see Intercept Help Messages). This option is on by default and should remain on unless you only want to display WM_HELP and WM_TCARD messages.

•	Intercept Help Messages
This option captures and displays WM_HELP and WM_TCARD messages sent from an application and displays them in the WinHelp BugHunter 32-bit output window. Be sure that Intercept Help Messages and Spy on WinHelp are enabled when you debug What’s This? Help. Another potential use of this option is to verify that your application is receiving the appropriate Windows messages. This option is of greatest interest to developers and Help authors who are acquainted with software development techniques.

•	Always on Top
This option displays the WinHelp BugHunter 32-bit window on top of all other applications even when BugHunter is not the active application.

•	View Context IDs (Map Numbers) in Hex
This option displays Context IDs in Hexadecimal notation.

•	Text and Background Color
These options let you modify the text and the background color in the WinHelp BugHunter 32-bit output window.

See Also

Setting WinHelp BugHunter Options


Setting BugHunter Options
Setting WinHelp BugHunter 32-bit options

To set WinHelp BugHunter 32-bit options:

1	From the View menu, select Options. The WinHelp BugHunter 32-bit Options dialog appears.

2	Select Spy on WinHelp to view all WinHelp activity in BugHunter’s output window.

3	Select Intercept Help Messages to capture and display WM_HELP and WM_TCARD messages sent from an application in BugHunter’s output window.

4	Select Always on Top to always keep the BugHunter window in view, even if it’s not the current application.

5	Select View Context IDs in Hex to display context IDs in hexadecimal notation (the default is decimal).

6	To change the text or background colors of the BugHunter window, click Text Color or Background Color and select the colors from the grid.

7	Click Apply to leave the WinHelp BugHunter 32-bit Options dialog open so you can set further options.

8	Click OK to close the dialog and save the new settings.

See Also

Overview of WinHelp BugHunter Options


Enable/Disable Button
Enable/Disable option

When this option is on, WinHelp BugHunter 32-bit is active. All WinHelp activity and Help messages are reported in the WinHelp BugHunter output window. If this option is off, no reporting takes place. When you start BugHunter, it is enabled by default.


Copying the BugHunter Log to the Clipboard
Copying the WinHelp BugHunter 32-bit data to the Clipboard

The information that appears in the BugHunter window is text that you can copy to the Windows Clipboard and paste into other files. This is especially useful if you want to send an e-mail message to the developer.

To copy WinHelp BugHunter 32-bit text to the Clipboard:

1	From the BugHunter window, highlight the text that you want to copy.

2	From the Edit menu, select Copy. The data is copied to the Windows Clipboard so you can paste it into an e-mail message or other files.


Clearing the BugHunter Window
Clearing the WinHelp BugHunter 32-bit window

The WinHelp BugHunter 32-bit window clears when you close it so that each time BugHunter is started, an empty window displays. As you are working with BugHunter, you may want to clear the window without restarting the program.

To clear the WinHelp BugHunter 32-bit window:

•	From the Edit menu, select Clear All.


Checking Map Numbers in a Help File
Checking specific context IDs (map numbers) in Help files

You can enter a Context ID (map number) and then ask BugHunter to display the corresponding topic. You can also use this procedure to verify the presence of a particular Context ID in a Help file.

To test a map number:

1	From the Tools menu, choose Test Context ID. The Test Context ID dialog appears.

2	Click the Browse button, select the Help file you want to use, and click Open.

3	In Context ID to test, enter the map number.

4	Select View in a Popup window if you want to view the Help topic in a popup window. When this feature is not selected, the Help topic appears in a regular Help window.

5	Click Test. The topic associated with the map number is displayed.

6	Click Done to close the dialog.


Viewing Map Numbers as Hexadecimal
Viewing context IDs (map numbers) in hexadecimal notation

You can view map numbers in decimal or hexadecimal notation. You may find this option useful if your application developer is generating Context IDs for the project and they are provided to you in hexadecimal notation. The default format is decimal.

To display map numbers as hexadecimal:

1	From the View menu, select Options. The WinHelp BugHunter 32-bit Options dialog appears.

2	Select View Context IDs in Hex so it displays a checkmark.

3	Click OK.


Annotations
Adding annotations

Annotations are comments or notes that you add to an output file. Use them whenever you need to clearly explain, with a little extra detail, information about your Context IDs.

To insert an annotation in the WinHelp BugHunter 32-bit output:

1	Click an insertion in the BugHunter window where you want to insert the annotation.

2	From the Edit menu, select Annotate. The Annotation dialog appears.

3	Enter the annotation text, and then click OK.

4	The text is inserted into the BugHunter window.


Save BugHunter's Output  as a Text File
Saving WinHelp BugHunter 32-bit's output as a text file

You can save the information displayed in the BugHunter window as a text file that you can in turn, share with your application developers.

To save WinHelp BugHunter 32-bit output to a text file:

1	From the File menu, select Save. The Save As dialog appears.

2	Navigate to the drive and folder where you want to save the text file.

3	In File name, enter a name for the text file.

4	Click Save.

Note: This feature is even more useful if you add annotations to your text files.


Expert Mode

WinHelp BugHunter’s Expert Mode compresses output to the WinHelp BugHunter window. When Expert Mode is enabled, BugHunter will generate fewer blank lines between each line of output. In addition, BugHunter will not expand short Macro names. Expert Mode uses macro syntax similar to the one shown in the following example:

The Macro "Jump ID" is displayed as "JI"

To enable Expert Mode:

•	From the View menu, select Expert Mode. After you enable it, the BugHunter window displays the message "Expert Mode is ON" and the View menu displays a checkmark next to the Expert Mode option.

To disable Expert Mode:

•	From the View menu, select Expert Mode. After you disable it, the BugHunter window displays the message "Expert Mode is OFF" and the View menu removes the checkmark from the Expert Mode option.


Understanding BugHunter Data
Understanding WinHelp BugHunter data

WinHelp BugHunter notes an "event" when:

•	A call is made to WinHelp—that is, any time Windows Help is called while BugHunter is active. The event log specifies the type of Help call and any parameters that were passed with the call, enabling you to track the information that the application is passing to WinHelp. BugHunter reports the following data for each event:

•	Function Call, Window Handle, Help System, Help Command, Help Topic Map Number

If the application uses any of the new Windows 95 WinHelp commands (HELP_WM_HELP or HELP_CONTEXTMENU), BugHunter reports additional data:

•	Function Call, Window Handle, Help System, Help Command, Pointer, Control Type, Control Text, Control ID, Topic Map Number (see the Glossary.)

•	A call is made within a Help file, such as a macro call. In this case, the macro is displayed in BugHunter.

•	A WM_Help or WM_TCARD message is sent between an application and a Help file. In this case, the message is displayed.

The following events may appear in your BugHunter event log:

HELP_COMMAND,<macro name>(<parameters>)

A call was made to a WinHelp macro. The macro name and any applicable parameters are also listed.

HELP_CONTENTS

A call was made to the Contents topic of the Help system.

HELP_CONTEXT,<Context ID>

A call was made to the context-sensitive Help topic indicated by the map number.

HELP_CONTEXTPOPUP,<Context ID>

A call was made to the context-sensitive Help topic indicated by the map number. The call specified that the topic was to be displayed in a popup window.

HELP_FORCEFILE,<file name>

A call was made to WinHelp, specifying the Help file to be displayed. The name of the Help file is passed as a parameter.

HELP_HELPONHELP

A call was made to the standard Help system "Help on Help." This is sometimes labeled "How to Use Help" in an application’s Help menu.

HELP_KEY,<keyword>

A call was made to WinHelp to display the topic containing the specified keyword. The keyword is passed as a parameter.

HELP_MULTIKEY,<table footnote>,<keyword>

A call was made to WinHelp to display the topic containing the specified keyword. This type of call is used when the keyword is in an alternate keyword table. The table footnote character and the keyword are passed as parameters.

HELP_PARTIALKEY,<keyword>

A call was made to WinHelp to display the topic containing the specified keyword. The keyword is passed as a parameter.

HELP_QUIT

A call was made to WinHelp indicating that Help is no longer needed.

HELP_SETCONTENTS,<topic name>

A call was made to the SetContents macro. This macro defines the topic ID of the topic that is the "Contents" topic of the Help system. The topic ID of the topic is included as a parameter.

HELP_SETWINPOS

A call was made to the SetWinPos macro. This macro specifies the size and position of a primary or secondary Help window.

HELP_UNKNOWN

A non-standard call was made to WinHelp.

HELP_WM_HELP

A call was made to the WinHelp API in response to the user clicking on a control after clicking on the What’s This? question mark on the caption bar of a dialog box.

HELP_CONTEXTMENU

A call was made to the WinHelp API in response to a right-click entry made by a user.


Glossary

Context ID
Alternate term for Map ID. A number assigned uniquely to a Help topic allowing WinHelp to identify it when receiving a call to display the topic. Map numbers are paired with Topic IDs in map files, and are also placed in application source code. When a help system is compiled, the information in its map file (if it has one) is built into the resulting HLP file.

Context String
Former term for Topic ID.

Control Type
The object type of a control, such as a Dialog Box, Edit Field or Static Text.

Control Text
If the control contains text, it is listed as ‘control text’ in BugHunter’s display window. (This can be empty.)

Control ID
A number assigned uniquely to a control to identify it in the application’s source code.

Map File
A text file containing Topic IDs (character strings) and their corresponding Context IDs (map numbers). Map files are one of the resources included in HLP files when they are compiled. Map files typically have the extension HH or HM. If a map file is used in a Help project, it must be included in the [MAP] section of the HPJ file. (RoboHELP does this automatically when you include a map file in the Setup Project utility.)

Map ID
Alternate term for Context ID. A number assigned uniquely to a Help topic allowing WinHelp to identify it when receiving a call to display the topic. Map numbers are paired with Topic IDs in map files, and are also placed in application source code. When a help system is compiled, the information in its map file (if it has one) is built into the resulting HLP file.

Topic ID
Formerly called Context String. A character string that uniquely identifies a Help topic.


eHelp Corporation headquarters

eHelp Corporation is the worldwide leader in Help authoring solutions. Software developers, Help authors, technical writers, and documentation experts worldwide turn to eHelp Corporation for state-of-the-art Help authoring and Internet/intranet solutions.

Corporate Headquarters

Address:	eHelp Corporation 7777 Fay Avenue, Suite 201 La Jolla, CA 92037 U.S.A.
Telephone:	1-858-551-2485
Fax:	1-858-551-2486
World Wide Web:	www.blue-sky.com
Office Hours:	Monday to Friday 6:00 A.M. to 5:00 P.M. Pacific Time


Sales

eHelp Corporation’s professional sales staff is ready to answer your sales questions Monday to Friday from 6:00 A.M. to 5:00 P.M. Pacific Time.

Contact your sales representative to hear about the latest products, the Subscription Plan, training, upgrade options and prices, and more. If you have a technical question or problem, please contact Technical Support.

Contacting your eHelp Corporation Sales Representative

Sales Phone:	1-800-677-4946
International (including Canada):	1-858-459-6365
Sales Fax:	1-858-459-6366
World Wide Web:	www.blue-sky.com
Sales Email:	sales@blue-sky.com
When sending email, please include your company name, city, and state to ensure your request is handled promptly.


eHelp Corporation Web site


Technical Support

At eHelp Corporation, we work hard to provide you with intuitive technical products. Additionally, we try to provide superior online and print documentation to enable you to work independently. If you have a technical question that you can’t answer with the provided tools, please contact our Technical Support department. All of our Technical Support representatives are eager to answer your questions and help you create the best Help systems possible.

Note: You must be a registered user to access eHelp Corporation support services. eHelp Corporation support services are subject to the prices, terms, and conditions in place at the time the service is used.

eHelp Corporation’s Technical Support services includes email, telephone, and Web-based support on our corporate Web site.

Help Us Help You

When contacting Technical Support via phone or email, please provide the following information for the fastest possible service:

•	Product serial number (registration number)

•	Your name, company name, and phone number

•	Exact product name and version number

•	Type of operating system (e.g., Windows 95)

•	Version of Microsoft Word (if using RoboHELP for WinHelp)

•	Browser and version (if creating HTML-based Help)

•	Complete description of the issue, including steps to reproduce it

•	Exact wording of any messages displayed when you encountered the problem

•	Steps taken to resolve the problem

•	All previous email threads with eHelp Corporation about the issue, if any

For current hours of operation and details about all support offerings, please:

•	Visit our Web site.

•	Email us at supportnews@blue-sky.com to receive an automated reply listing all of your support options.

•	Call us at 858-551-2194.


eHelp Corporation Knowledge Base


Documentation feedback

At eHelp Corporation, we strive to produce the highest quality documentation products and welcome your feedback. If you have comments or suggestions about our online Help or printed guides, you can email us.

Please include the following information with your feedback:

•	Product name and version number

•	Printed manual or online Help

•	Topic title (for online Help)

•	Page number (for printed manual)

•	Brief description of content (for example, are you reviewing step-by-step instructions that are inaccurate, grammatical errors in a specific paragraph, information that requires clarification or more details, etc.)

•	Your suggestion for how to correct/improve documentation

Please send email messages to:

documentation@blue-sky.com

Keep in mind, this email address is only for documentation feedback; you will not receive a reply. If you have a technical question, please contact Technical Support.


Other helpful resources

A good list of resources can make all the difference in terms of support, guidance, and inspiration. As the worldwide leader in Help authoring solutions, eHelp Corporation leads the way by offering a list of helpful resources on our Web site.

You’ll find the latest Help authoring resource information – including books, periodicals, online forums, helpful Internet links, training, and more.


WinHelp 2000

We are unable to detect Internet Explorer or an Internet connection on your system, so we are unable to display eHelp Corporation’s Web site.

This Help file uses WinHelp 2000, which extends the WinHelp viewer to provide full HTML and Web functionality without leaving WinHelp. WinHelp 2000 gives you all the benefits of HTML without the risk of switching to a new Help architecture.

WinHelp 2000 uses the same display engine as Microsoft’s Internet Explorer and HTML Help, so all of the rich content of the World Wide Web can be displayed and integrated into any standard Windows Help system.

If you use a browser other than Internet Explorer, use this alternative link:

 eHelp Corporation’s Web site


PC HelpDesk

We are unable to detect ODBC with an Internet connection on your system, so we are unable to display eHelp Corporation’s Knowledge Base.

Our Knowledge Base was created using PC HelpDesk – an eHelp Corporation tool included in RoboHELP Office. PC HelpDesk packages your product knowledge base into a customized HelpDesk you design, create, and maintain. Customers simply click on the HelpDesk link from your system’s Help file, and they have instant access to valuable information about your products. A well designed HelpDesk can lower your technical support costs and increase customer satisfaction by providing an easy way for your customers to get answers to their most common questions.


Premium Support

Premium Support entitles plan members to priority Technical Support access through a dedicated telephone line and a dedicated email address. Plan members receive direct access to eHelp Corporation’s seasoned Senior Technical Support Engineers.

Premium Support plans are available for current and previous versions of eHelp Corporation products.